Poglobljena primerjava setup.py in pyproject.toml za upravljanje paketov Python, ki zajema najboljše prakse, strategije migracije in sodobna orodja.
Struktura paketa Python: Setup.py proti Pyproject.toml - Celovit vodnik
Dolga leta je bila datoteka setup.py temelj upravljanja paketov Python. Vendar se je pokrajina razvila in pyproject.toml se je pojavil kot sodobna alternativa. Ta celovit vodnik raziskuje razlike med tema dvema pristopoma in vam pomaga razumeti, kateri je pravi za vaš projekt in kako učinkovito upravljati svoje pakete Python.
Razumevanje osnov
Kaj je paket Python?
Paket Python je način organiziranja in distribucije vaše kode Python. Omogoča vam, da povezano kodo združite v hierarhijo imenikov, zaradi česar je vaša koda bolj modularna, večkrat uporabna in enostavnejša za vzdrževanje. Paketi so bistveni za deljenje vaše kode z drugimi in za upravljanje odvisnosti v vaših projektih.
Vloga metapodatkov paketa
Metapodatki paketa zagotavljajo bistvene informacije o vašem paketu, kot so njegovo ime, različica, avtor, odvisnosti in vstopne točke. Te metapodatke upravljavci paketov, kot je pip, uporabljajo za namestitev, nadgradnjo in upravljanje vaših paketov. Zgodovinsko gledano je bil setup.py primarni način za določanje teh metapodatkov.
Setup.py: Tradicionalni pristop
Kaj je Setup.py?
setup.py je skript Python, ki uporablja knjižnico setuptools za definiranje strukture in metapodatkov vašega paketa. To je dinamično izvršena datoteka, kar pomeni, da za konfiguracijo paketa izvaja kodo Python.
Ključne komponente Setup.py
Tipična datoteka setup.py vključuje naslednje komponente:
- Ime paketa: Ime vašega paketa (npr.
my_package). - Različica: Številka različice vašega paketa (npr.
1.0.0). - Podatki o avtorju in vzdrževalcu: Podrobnosti o avtorju in vzdrževalcu paketa.
- Odvisnosti: Seznam drugih paketov, od katerih je odvisen vaš paket (npr.
requests >= 2.20.0). - Vstopne točke: Definicije za skripte ukazne vrstice ali druge vstopne točke v vaš paket.
- Podatki paketa: Ne-kodne datoteke (npr. konfiguracijske datoteke, podatkovne datoteke), ki bi morale biti vključene v paket.
Primer Setup.py
```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='Preprost paket Python', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```Prednosti Setup.py
- Poznavanje: To je tradicionalni in dobro znan pristop, zato ga mnogi razvijalci že poznajo.
- Prilagodljivost: Ker gre za skript Python, ponuja visoko stopnjo prilagodljivosti. Po potrebi lahko izvedete kompleksno logiko in prilagodite postopek gradnje.
- Razširljivost: Setuptools ponuja bogat nabor funkcij in ga je mogoče razširiti z ukazi in razširitvami po meri.
Slabosti Setup.py
- Dinamično izvrševanje: Dinamična narava
setup.pyje lahko varnostno tveganje, saj med postopkom gradnje izvaja poljubno kodo. - Implicitne odvisnosti:
setup.pyse pogosto zanaša na implicitne odvisnosti, kot je setuptools sam, kar lahko vodi do nedoslednosti in napak. - Kompleksnost: Za kompleksne projekte lahko
setup.pypostane velik in težko vzdržljiv. - Omejena deklarativna konfiguracija: Velik del metapodatkov paketa je določen imperativno in ne deklarativno, zaradi česar je težje razmišljati o tem.
Pyproject.toml: Sodobna alternativa
Kaj je Pyproject.toml?
pyproject.toml je konfiguracijska datoteka, ki uporablja format TOML (Tom's Obvious, Minimal Language) za definiranje gradbenega sistema in metapodatkov vašega paketa. To je deklarativni pristop, kar pomeni, da določite, kaj želite doseči, ne pa kako to doseči.
Ključni oddelki Pyproject.toml
Tipična datoteka pyproject.toml vključuje naslednje oddelke:
[build-system]: Določa gradbeni sistem, ki ga želite uporabiti (npr.setuptools,poetry,flit).[project]: Vsebuje metapodatke o projektu, kot so njegovo ime, različica, opis, avtorji in odvisnosti.[tool.poetry]ali[tool.flit]: Oddelki za konfiguracije, specifične za orodje (npr. Poetry, Flit).
Primer Pyproject.toml (s Setuptools)
```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "Preprost paket Python" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```Primer Pyproject.toml (s Poetry)
```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "Preprost paket Python" authors = ["John DoePrednosti Pyproject.toml
- Deklarativna konfiguracija:
pyproject.tomlponuja deklarativni način definiranja metapodatkov vašega paketa, zaradi česar je razumljivejši in lažji za vzdrževanje. - Standardiziran gradbeni sistem: Določa gradbeni sistem, ki ga želite uporabiti, s čimer zagotavlja dosledne gradnje v različnih okoljih.
- Izboljšano upravljanje odvisnosti: Orodja, kot sta Poetry in Pipenv, se brezhibno integrirajo s
pyproject.toml, da zagotovijo robustne funkcije upravljanja odvisnosti. - Zmanjšana varnostna tveganja: Ker gre za statično konfiguracijsko datoteko, odpravlja varnostna tveganja, povezana z dinamičnim izvrševanjem kode med postopkom gradnje.
- Integracija s sodobnimi orodji:
pyproject.tomlje standard za sodobna orodja za pakiranje Python, kot so Poetry, Pipenv in Flit.
Slabosti Pyproject.toml
- Krivulja učenja: Razvijalci se bodo morda morali naučiti nove sintakse (TOML) in novega načina razmišljanja o upravljanju paketov.
- Omejena prilagodljivost: Morda ni primerna za visoko prilagojene gradbene procese, ki zahtevajo kompleksno logiko.
- Odvisnost od orodij: Izbrati in se boste morali naučiti uporabljati določen gradbeni sistem (npr. Setuptools, Poetry, Flit).
Primerjava Setup.py in Pyproject.toml
Tukaj je tabela, ki povzema ključne razlike med setup.py in pyproject.toml:
| Funkcija | Setup.py | Pyproject.toml |
|---|---|---|
| Stil konfiguracije | Imperativni (koda Python) | Deklarativni (TOML) |
| Gradbeni sistem | Implicitni (Setuptools) | Eksplicitni (določen v [build-system]) |
| Varnost | Potencialno manj varno (dinamično izvrševanje) | Bolj varno (statična konfiguracija) |
| Upravljanje odvisnosti | Osnovno (install_requires) |
Napredno (integracija s Poetry, Pipenv) |
| Orodja | Tradicionalno (Setuptools) | Sodobno (Poetry, Pipenv, Flit) |
| Prilagodljivost | Visoka | Zmerna |
| Kompleksnost | Lahko je visoka za kompleksne projekte | Na splošno nižja |
Strategije migracije: od Setup.py do Pyproject.toml
Migracija iz setup.py v pyproject.toml se morda zdi zastrašujoča, vendar je vredna naložba za dolgoročno vzdrževanje in doslednost. Tukaj je nekaj strategij, ki jih lahko uporabite:
1. Začnite z minimalnim Pyproject.toml
Ustvarite osnovno datoteko pyproject.toml, ki določa gradbeni sistem, nato pa postopoma migrirajte metapodatke iz setup.py v pyproject.toml.
2. Uporabite Setuptools s Pyproject.toml
Še naprej uporabljajte Setuptools kot svoj gradbeni sistem, vendar definirajte metapodatke projekta v pyproject.toml. To vam omogoča, da izkoristite prednosti pyproject.toml, hkrati pa še vedno uporabljate znano orodje.
3. Migrirajte na sodobno orodje, kot je Poetry
Razmislite o migraciji na sodobno orodje, kot je Poetry ali Pipenv. Ta orodja zagotavljajo celovite funkcije upravljanja odvisnosti in se brezhibno integrirajo s pyproject.toml.
Primer: Migracija na Poetry
- Namestite Poetry:
pip install poetry - Inicializirajte Poetry v vašem projektu:
poetry init(To vas bo vodilo pri ustvarjanju datotekepyproject.toml) - Dodajte svoje odvisnosti:
poetry add requests(ali druge odvisnosti) - Zgradite svoj paket:
poetry build
4. Uporabite orodja za avtomatizirano migracijo
Nekatera orodja lahko pomagajo avtomatizirati postopek migracije. Na primer, lahko uporabite orodja za pretvorbo datoteke setup.py v datoteko pyproject.toml.
Najboljše prakse za upravljanje paketov Python
1. Uporabite virtualno okolje
Vedno uporabite virtualno okolje, da izolirate odvisnosti svojega projekta od sistemske namestitve Python. To preprečuje konflikte in zagotavlja, da ima vaš projekt pravilne odvisnosti.
Primer uporabe venv:
Primer uporabe conda:
2. Natančno določite odvisnosti
Uporabite omejitve različic, da določite združljive različice svojih odvisnosti. To preprečuje nepričakovano vedenje, ki ga povzročijo nezdružljive posodobitve knjižnic. Za upravljanje odvisnosti uporabite orodja, kot je pip-tools.
Primer specifikacije odvisnosti:
``` requests >= 2.20.0, < 3.0.0 ```3. Uporabite dosleden gradbeni sistem
Izberite gradbeni sistem (npr. Setuptools, Poetry, Flit) in se ga držite. To zagotavlja dosledne gradnje v različnih okoljih in poenostavlja postopek pakiranja.
4. Dokumentirajte svoj paket
Napišite jasno in jedrnato dokumentacijo za svoj paket. To pomaga uporabnikom razumeti, kako uporabljati vaš paket, in olajša drugim, da prispevajo k vašemu projektu. Uporabite orodja, kot je Sphinx, za ustvarjanje dokumentacije iz vaše kode.
5. Uporabite neprekinjeno integracijo (CI)
Nastavite sistem CI (npr. GitHub Actions, Travis CI, GitLab CI), da samodejno sestavite, preizkusite in namestite vaš paket, kadar koli so v vaši kodi narejene spremembe. To pomaga zagotoviti, da je vaš paket vedno v delovnem stanju.
Primer konfiguracije GitHub Actions:
```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```6. Objavite svoj paket na PyPI
Delite svoj paket s svetom tako, da ga objavite v Python Package Index (PyPI). To olajša drugim namestitev in uporabo vašega paketa.
Koraki za objavo na PyPI:
- Registrirajte račun na PyPI in TestPyPI.
- Namestite
twine:pip install twine. - Sestavite svoj paket:
poetry buildalipython setup.py sdist bdist_wheel. - Naložite svoj paket na TestPyPI:
twine upload --repository testpypi dist/*. - Naložite svoj paket na PyPI:
twine upload dist/*.
Primeri iz resničnega sveta
Poglejmo si, kako nekateri priljubljeni projekti Python uporabljajo pyproject.toml:
- Poetry: Uporablja
pyproject.tomlza svoje upravljanje paketov. - Black: Neomajen formatirnik kode prav tako uporablja
pyproject.toml. - FastAPI: Sodoben, hiter (visokozmogljiv) spletni okvir za izdelavo API-jev s Pythonom ga prav tako uporablja.
Zaključek
pyproject.toml predstavlja sodobni standard za upravljanje paketov Python, ki ponuja deklarativni in varen način za določanje metapodatkov vašega paketa in upravljanje odvisnosti. Čeprav nam je setup.py dobro služil, je migracija na pyproject.toml vredna naložba za dolgoročno vzdrževanje, doslednost in integracijo s sodobnimi orodji. Z uporabo najboljših praks in uporabo pravih orodij lahko poenostavite svoj potek dela pri pakiranju Pythona in ustvarite visokokakovostne pakete za večkratno uporabo.